home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / batch / tbu11 / tbu11.doc < prev   
Encoding:
Text File  |  1989-03-26  |  10.3 KB  |  233 lines
  1.  
  2. tBU v1.1 - Batch Utility - Planet Terus
  3.  
  4. [ Lines beginning with  (*) are those added by a fan of
  5.   the program who thought the docs needed a bit of improvement ]
  6.  
  7. Usage:    tbu <option symbol arg1 arg2 ...> <option ... >
  8.  
  9. Sets the DOS environment symbol based on the option chosen.  tBU will
  10. process multiple sets of option-symbol-arg sets from left to right.
  11.  
  12. (*) The program's author has used the word "symbol" to mean what most 
  13. (*) people call a "variable" - as in: "environment symbol" means
  14. (*) "environment variable."
  15.  
  16. Symbols may be used in batch commands as %SYMBOL% (symbol must appear
  17. in all capital letters). The symbol set by tBU CAN be empty. To check
  18. for an empty symbol use something like:
  19.     IF (%SYMBOL%) == () echo It's empty
  20.     IF not (%SYMBOL%) == () echo It's not empty
  21.  
  22. ERRORLEVEL is returned as 255 if error occured. The option character
  23. may be either a dash (-) or a slash (/).
  24.  
  25. (*) I have not found that the environment variables need to be
  26. (*) typed in all caps. Not with DOS 3.1, anyway.
  27.  
  28. (*) I have found that the program will fail consistently if you type
  29. (*) the command-line switches, such as "-f" or whatever, in CAPS.
  30. (*) Maybe that won't happen to everyone, but I must always type them
  31. (*) in lower case to get them to work!
  32.  
  33. Options:
  34.   -f  Parse filename & extension.      <sym> <filespec>
  35.       Sets symbol to the filename portion of arg1. Any dot name/
  36.       extension separator is not changed.
  37.       ERRORLEVEL:  Length of resulting string.
  38.       Example:  tbu -f file c:\tbu.exe  sets file to tbu.exe
  39.                 tbu -f file c:\data.    sets file to data.
  40.                 tbu -f file c:\data     sets file to data
  41.  
  42.   -x  Parse file extension only.       <sym> <filespec>
  43.       Sets symbol to the extension portion of arg1. The dot name/
  44.       extension separator is always removed.
  45.       ERRORLEVEL:  Length of resulting string.
  46.       Example:  tbu -e ext c:\cmd\tbu.exe  sets ext to exe
  47.  
  48. (*) The "." from the file name is NOT preserved in an environment
  49. (*) variable created with the "-x" switch.
  50.  
  51.   -n  Parse name only.                 <sym> <filespec>
  52.       Sets symbol to the name portion of arg1. The dot name/
  53.       extension separator is always removed.
  54.       ERRORLEVEL:  Length of resulting string.
  55.       Example:  tbu -n name c:\tbu.exe  sets name to tbu
  56.  
  57. (*) The "." from the file name is NOT preserved in an environment
  58. (*) variable created with the "-n" switch.
  59.  
  60. (*) Here is an instance in which you can stack commands on one
  61. (*) line. Let's say your %1 parameter for a batch file is a file
  62. (*) name, complete with extension. You could get the primary name
  63. (*) and the extension into two different variables in two different
  64. (*) passes, like this:
  65. (*)                      tbu -n name %1
  66. (*)                      tbu -x ext %1
  67.  
  68. (*) But why not do it in one pass? Like this:
  69. (*)          tbu -n name %1 -x ext %1
  70. (*) Works fine.
  71.  
  72.   -l  Parse disk drive letter only.    <sym> <filespec>
  73.       Sets symbol to the drive letter portion of arg1. The colon
  74.       drive/name separator is always removed.
  75.       ERRORLEVEL:  Length of resulting string.
  76.       Example:  tbu -d drive c:\tbu.exe  sets drive to c
  77.  
  78.   -c  Input character from keyboard.   <sym> [prompt] [valid] [secs]
  79.       Sets symbol to the upper case value of the character entered.
  80.       Optional prompt (may be ""). Optional valid characters, are
  81.       not case sensitive. Optional seconds for timed input. Accepts
  82.       printable keys only.
  83.       ERRORLEVEL:  ASCII code of character entered, 0 = timeout.
  84.       Example:  tbu -c ans "Ok (Y/N)?"  sets ans to any & prompts.
  85.       Example:  tbu -c ans "" yn        sets ans to Y or N.
  86.       Example:  tbu -c ans "" "" 20     sets ans to any & times 20 secs.
  87.  
  88. (*) It appears as if it's possible to use a  \  character to delimit
  89. (*) quote marks if you want them to be part of the prompt line. That
  90. (*) is, if you wanted your prompt line to read:
  91. (*)            What's your "handle" today?
  92. (*) *with* the quotes, you should make the instruction look something like:
  93. (*) tbu -c ans "What's your \"handle\" today? "
  94.  
  95. (*) If you use the -c operator and you have not specified a particular
  96. (*) string to be used for the response, and if you hit ENTER, it looks
  97. (*) as if a single space is entered into the variable you specify
  98. (*) in the command. In other words, it creates the variable and puts a
  99. (*) space - or maybe a NUL character, I dunno - into the variable.
  100.  
  101. (*) Note: if you use a time-delay and the program times out, you
  102. (*) get a moderately loud, shrill beep out of it. Just be warned,
  103. (*) it's not especially restful.
  104.  
  105.   -s  Input string from keyboard.      <sym> [prompt] [max length]
  106.       Sets symbol to the string entered. Optional prompt (may
  107.       be ""). Optional max input length (128 chars default).
  108.       ERRORLEVEL:  Length of string entered.
  109.       Example:  tbu -s user "Your name: "  sets user to string.
  110.  
  111. (*) In other words, the program sends the prompt:
  112. (*)                   Your name:
  113. (*) to the screen. Type something and hit ENTER. Then
  114. (*) an environment variable "USER" is written, containing
  115. (*) whatever you typed in response.
  116.  
  117. (*) In this case if you press ENTER in response to the prompt,
  118. (*) the program does NOT create a variable having the specified name.
  119.  
  120. (*) When using either the -s or -c options, you can include ANSI.SYS
  121. (*) cursor positioning commands in the prompt text. Using <esc> to mean
  122. (*) the <esc> character (alt 27), here's an example:
  123.  
  124. (*) tbu -s ans "<esc>[2J<esc>[14;8HThis is the prompt text: "
  125.  
  126. (*) Result: clears the screen and places the prompt line beginning
  127. (*) at row 14, column 8. ANSI.SYS text attribute commands can also
  128. (*) be placed into the prompt line this way.
  129.  
  130. (*) The "max length" function mentioned in the docs above does not
  131. (*) appear to work at all.
  132.  
  133. (*) Other undocumented features: if you use the -s switch and
  134. (*) create a prompt line, while entering text on the prompt line
  135. (*) you can use CTRL W to delete a word to the left of the cursor.
  136. (*) You can use CTRL U to clear the *entire* prompt line.
  137.  
  138.   -r  Get DOS revision.                <sym> [major|minor|both]
  139.       Sets symbol to the desired portion of the DOS version.
  140.       Default = Both.
  141.       ERRORLEVEL:  None.
  142.       Example:  tbu -r rev major
  143.  
  144.   -d  Get system date.                 <sym> <format>
  145.       Sets symbol to the system date in the specified format.
  146.       The format is embedded in a string:  $[modifier]<element type>
  147.       Element types:        Allowable modifiers:
  148.           y = year              [a for 2 digit year]
  149.           m = month             [0_wWaA]
  150.           d = day of month      [0_]
  151.           j = Julian date       [0_]
  152.           k = day of week       [0_wWaA] (numeric Sun=0, Mon=1,...)
  153.       Modifiers for numeric values:
  154.           0 = zero pad on left
  155.           _ = space pad on left
  156.       Modifiers for string values:
  157.           w = full word instead of number (W = all upper case)
  158.           a = abbreviated word instead of number (A = all upper case)
  159.       ERRORLEVEL:  None.
  160.       Example:  tbu -d date "The date is: $wk, $wm, $0d $y"
  161.  
  162. (*) The result of the example is an environment variable "DATE"
  163. (*) containing the string:
  164. (*)             The date is: Monday, March, 13 1989
  165. (*) Note that the omission of a comma in the above instruction leads
  166. (*) to no comma following the "13" in the environment variable itself.
  167. (*) Another example:
  168.  
  169. (*)                 tbu -d dt $0m-$d-$ay
  170. (*) This creates a variable "dt" containing something like
  171. (*) 02-13-89 if it were 13 February, 1989, or something like
  172. (*) 11-15-89 if it were 15 November, 1989.
  173.  
  174.   -t  Get system time.                 <sym> <format>
  175.       Sets symbol to the system time in the specified format.
  176.       The format is embedded in a string:  $[modifier]<element type>
  177.       Element types:        Allowable modifiers:
  178.           h = hours             [0_]
  179.           m = minutes
  180.           s = seconds
  181.           a = AM/PM             (h = 1-12 if present)
  182.           d = daylight          (Y = daylight savings time in effect)
  183.       Modifiers for numeric values:
  184.           0 = zero pad on left
  185.           _ = space pad on left
  186.       ERRORLEVEL:  None.
  187.       Example:  tbu -t time "The time is: $0h:$m:$s $a"
  188.  
  189.   -b  Substitute pattern for data.     <sym> <patt> <data> <string>
  190.       Replaces pattern with data in string.  Sets symbol to
  191.       the new string.
  192.       ERRORLEVEL:  Length of new string.
  193.       Example:  tbu -b new "change this" "to this" "Point: change this"
  194.  
  195. (*) This last option is really a nice idea but the above docs make it
  196. (*) rather obscure in terms of how you use it, exactly. The closest I
  197. (*) can figure it is:
  198.  
  199. (*) the first string is what you want to change
  200. (*) the second one is what you want to change it to.
  201. (*) the third is the COMPLETE string in which the "change from"
  202. (*) text appears. The phrase "replaces pattern with data in string"
  203. (*) in the docs above don't mean a damned thing to me!
  204.  
  205. (*) So if you ALREADY have an environment variable "xx" which contains this
  206. (*) string:   E:ED.DEF   and you wanted to elimiate the "DEF"
  207. (*) and change it to "TXT," your instruction would be:
  208.  
  209. (*) tbu -b xx "DEF" "TXT" "E:ED.DEF" - this does not appear to involve
  210. (*) case-sensitivity. Note that if you did NOT include the FULL string
  211. (*) "E:ED.DEF" then the environment variable "xx" would be changed
  212. (*) to read ONLY "TXT" - and NOT "E:ED.TXT".
  213.  
  214. (*) Why the author designed it this way, I don't know. It thus sort
  215. (*) of is, but really isn't, a string search/replace utility. It's only
  216. (*) useful if you ALREADY KNOW what the contents of the environment
  217. (*) variable are. In which case: why not just alter it in its entirety
  218. (*) in your batch file?
  219.  
  220. (*) Note that if you must specify a  \  character in the string-search
  221. (*) routine, TBU appears to require that you delimit it with a second
  222. (*) backslash character. Thus: \\. So the string C:\AUTOEXEC.BAT
  223. (*) would have to be represented as: C:\\AUTOEXEC.BAT. However, this
  224. (*) may not always hold true. As said, this part of the program is
  225. (*) rather obscure.
  226.  
  227. (*) Criticism of the docs notwithstanding, this is a GOOD program -
  228. (*) kudos (and thanks) to the author for writing it.
  229.  
  230. Another Smileware program from Planet Terus <PT>.  If you like it, send
  231. us a smile "*<B-)" at IFNA(tm) 104/43 -- (303) 469-7161.
  232.  
  233.